إتقان JavaScript Temporal ZonedDateTime: دليلك لإجراء حسابات زمنية خالية من الأخطاء ومراعية للمناطق الزمنية

في عالمنا الذي يزداد ترابطًا، نادرًا ما تعمل التطبيقات ضمن حدود منطقة زمنية واحدة. من جدولة اجتماعات الفرق الدولية وإدارة الأحداث العالمية إلى تسجيل المعاملات المالية عبر القارات، يعد التعامل مع التواريخ والأوقات بدقة ووضوح تحديًا مستمرًا وغالبًا ما يكون معقدًا للمطورين. كائنات Date التقليدية في JavaScript، على الرغم من أنها عملية لعمليات الوقت المحلية البسيطة، إلا أنها تواجه صعوبات معروفة في التعامل مع تعقيدات المناطق الزمنية، وتغييرات التوقيت الصيفي (DST)، وأنظمة التقويم المختلفة. وغالبًا ما تؤدي إلى أخطاء دقيقة يمكن أن يكون لها آثار كبيرة على تجربة المستخدم وسلامة البيانات ومنطق العمل.

هنا يأتي دور واجهة برمجة التطبيقات Temporal API في JavaScript، وهي حل حديث وقوي ومنتظر بشدة مصمم ليحل محل كائن Date القديم. من بين أساسياتها القوية الجديدة، يبرز Temporal.ZonedDateTime باعتباره حجر الزاوية لإجراء حسابات تراعي المناطق الزمنية حقًا. فهو يمثل لحظة زمنية محددة لا لبس فيها، مرتبطة بمنطقة زمنية معينة، مما يجعله لا غنى عنه لأي تطبيق يخدم جمهورًا عالميًا. سيتعمق هذا الدليل الشامل في ZonedDateTime، مستكشفًا ميزاته، وموضحًا تطبيقاته العملية، ومحددًا أفضل الممارسات لدمجه في سير عمل التطوير العالمي الخاص بك.

تحدي الوقت العالمي: لماذا التواريخ والأوقات صعبة

قبل أن نتبنى الحلول التي تقدمها Temporal، دعونا نحلل لماذا كانت إدارة التاريخ والوقت صداعًا مستمرًا في JavaScript وبيئات البرمجة الأخرى. تنبع المشكلة الأساسية من الغموض المتأصل في تمثيل "نقطة في الزمن" بدون إطار مرجعي واضح.

قيود كائنات Date القديمة

يعتبر كائن Date الأصلي في JavaScript معيبًا بشكل أساسي للتطبيقات العالمية لأنه يحاول أن يكون شيئين في آن واحد: لحظة زمنية محددة (مثل طابع زمني UTC) وتمثيل محلي لتلك اللحظة. غالبًا ما يؤدي هذا الطابع المزدوج إلى الارتباك والأخطاء:

• افتراضات المنطقة الزمنية الضمنية: عند إنشاء new Date() بدون وسائط، فإنه يفترض افتراضيًا المنطقة الزمنية المحلية للنظام. وعندما تقوم بتحليل سلسلة نصية مثل "2023-10-27T10:00:00"، غالبًا ما يتم تفسيرها على أنها وقت محلي، ولكن بدون معلومات صريحة عن المنطقة الزمنية، يعد هذا تعليمًا غامضًا.
• الكائنات القابلة للتغيير: كائنات Date قابلة للتغيير (mutable)، مما يعني أن عمليات مثل setHours() تعدل الكائن الأصلي مباشرة. هذا يجعل تتبع التغييرات صعبًا ويمكن أن يؤدي إلى آثار جانبية غير مقصودة، خاصة في التطبيقات المعقدة حيث يتم تمرير التواريخ.
• الحسابات الصعبة: إجراء حسابات مثل إضافة "ثلاث ساعات" أو "يومين" دون مراعاة تحولات المناطق الزمنية أو تغييرات التوقيت الصيفي بشكل صحيح عرضة للخطأ. التعامل اليدوي مع انتقالات التوقيت الصيفي، التي تحدث في أوقات وتواريخ مختلفة عالميًا، مهمة ضخمة.
• التحليل غير المتسق: تحليل السلاسل النصية غير موثوق به بشكل كبير عبر المتصفحات ومحركات JavaScript المختلفة، مما يؤدي إلى سلوك غير قياسي عند تفسير سلاسل التواريخ.
• لا يوجد تمييز واضح: لا توجد طريقة واضحة لتمثيل تاريخ محدد بدون وقت، أو وقت بدون تاريخ، أو مدة، أو لحظة بدون منطقة زمنية.

التأثير الحقيقي لأخطاء المناطق الزمنية

تأمل هذه السيناريوهات حيث يمكن أن يتسبب التعامل غير الكافي مع التاريخ/الوقت في مشاكل كبيرة:

• اجتماعات فائتة: يقوم فريق في لندن بجدولة اجتماع في "الساعة 3 مساءً" مع زملاء في نيويورك. بدون تحويل مناسب للمنطقة الزمنية، قد يفسر فريق نيويورك هذا على أنه الساعة 3 مساءً بتوقيتهم المحلي، بدلاً من الساعة 3 مساءً بتوقيت لندن (والتي ستكون 10 صباحًا في نيويورك خلال التوقيت القياسي).
• توقيتات أحداث غير صحيحة: يمكن أن يساء فهم مؤتمر عبر الإنترنت تم الإعلان عن بدئه في "الساعة 9:00 صباحًا بتوقيت المحيط الهادئ" من قبل الحاضرين في مناطق أخرى إذا لم تقم شاشتهم المحلية بالتحويل بشكل صحيح.
• معاملات مالية خاطئة: تتطلب البنوك أو البورصات التي تعمل عبر الحدود طوابع زمنية دقيقة لا لبس فيها لكل معاملة للحفاظ على سجلات المراجعة وضمان الامتثال التنظيمي. ساعة في غير مكانها يمكن أن تؤدي إلى خسائر بالملايين أو نزاعات قانونية.
• مشاكل تحليل السجلات: تصبح سجلات الخادم المختومة بالأوقات المحلية من خوادم مختلفة في مناطق جغرافية مختلفة مستحيلة الربط والتحليل بدقة بدون توحيد.
• تأخيرات في اللوجستيات والتسليم: جدولة تسليم "غدًا الساعة 10 صباحًا" عبر القارات تتطلب مراعاة المنطقة الزمنية للمستلم، وليس فقط منطقة المرسل.

تسلط هذه التحديات الضوء على الحاجة الماسة لواجهة برمجة تطبيقات قوية وصريحة وواضحة للتعامل مع التاريخ والوقت. وهذا هو بالضبط ما تهدف JavaScript Temporal إلى تقديمه.

تقديم JavaScript Temporal: نهج حديث للتواريخ والأوقات

إن Temporal API هي كائن عالمي جديد تمامًا يوفر واجهة برمجة تطبيقات بديهية وموثوقة للعمل مع التواريخ والأوقات. يعالج أوجه القصور في كائن Date القديم من خلال تقديم مجموعة من الأنواع غير القابلة للتغيير والمميزة التي تفصل الاهتمامات بوضوح:

• Temporal.Instant: يمثل نقطة زمنية محددة لا لبس فيها، مستقلة عن أي تقويم أو منطقة زمنية. إنه في الأساس طابع زمني UTC عالي الدقة. مثالي لتسجيل وتخزين اللحظات الدقيقة.
• Temporal.PlainDate: يمثل تاريخًا تقويميًا (سنة، شهر، يوم) بدون أي معلومات عن الوقت أو المنطقة الزمنية. مفيد لأعياد الميلاد أو العطلات.
• Temporal.PlainTime: يمثل وقت ساعة الحائط (ساعة، دقيقة، ثانية، أجزاء من الثانية) بدون أي معلومات عن التاريخ أو المنطقة الزمنية. مفيد للروتين اليومي.
• Temporal.PlainDateTime: يجمع بين PlainDate و PlainTime. إنه تاريخ ووقت محدد في تقويم، ولكن لا يزال بدون منطقة زمنية. غالبًا ما يطلق عليه "تاريخ-وقت محلي" أو "تاريخ-وقت ساعة الحائط".
• Temporal.ZonedDateTime: نجم هذا الدليل. إنه PlainDateTime مرتبط بـ Temporal.TimeZone محدد. هذا هو النوع الذي يمثل بدقة لحظة معينة في منطقة زمنية معينة، معالجة التوقيت الصيفي والفروق الزمنية بشكل صحيح.
• Temporal.Duration: يمثل فترة زمنية، مثل "3 ساعات و 30 دقيقة" أو "5 أيام". يستخدم لإجراء العمليات الحسابية مع أنواع Temporal الأخرى.
• Temporal.TimeZone: يمثل منطقة زمنية محددة، يتم تحديدها بواسطة سلسلة منطقة زمنية IANA (على سبيل المثال، "Europe/London"، "America/New_York"، "Asia/Tokyo").
• Temporal.Calendar: يمثل نظام تقويم، مثل الميلادي، ISO 8601، الياباني، أو الصيني.

المبدأ الرئيسي وراء Temporal هو الوضوح. فأنت تعرف دائمًا بالضبط نوع معلومات التاريخ/الوقت التي تتعامل معها، وتتطلب العمليات منك أن تكون متعمدًا بشأن المناطق الزمنية والمدد والتقاويم. هذا يزيل الافتراضات الخفية والغموض الذي يعاني منه كائن Date القديم.

فهم المكونات الأساسية لـ ZonedDateTime

في جوهره، يجمع Temporal.ZonedDateTime بين ثلاث معلومات أساسية لتمثيل لحظة في الزمن بشكل لا لبس فيه بالنسبة لمنطقة جغرافية:

1. Temporal.PlainDateTime: يوفر هذا المكون مكونات السنة والشهر واليوم والساعة والدقيقة والثانية وأجزاء الثانية من التاريخ والوقت. بشكل حاسم، هذا هو وقت "ساعة الحائط"، مما يعني أنه ما ستراه على وجه الساعة أو التقويم في موقع معين، *دون* مراعاة أي قواعد منطقة زمنية بعد. على سبيل المثال، "2023-10-27 في الساعة 10:00:00".
2. Temporal.TimeZone: هذه هي مجموعة القواعد (مثل، الإزاحة عن UTC، تواريخ بدء/انتهاء التوقيت الصيفي) التي تحدد كيفية الحفاظ على الوقت في منطقة جغرافية معينة. يستخدم Temporal معرفات قاعدة بيانات المناطق الزمنية IANA (مثل، "America/Los_Angeles"، "Europe/Berlin"، "Asia/Dubai"). يوفر هذا المكون السياق اللازم لتفسير PlainDateTime.
3. offset (مشتق ضمنيًا): على الرغم من أنه ليس جزءًا صريحًا من معلمات المنشئ في معظم الحالات، إلا أن ZonedDateTime يعرف داخليًا إزاحته الدقيقة عن UTC في تلك اللحظة المحددة. تأخذ هذه الإزاحة في الاعتبار الإزاحة القياسية للمنطقة الزمنية وأي توقيت صيفي نشط. وتضمن أن مكون PlainDateTime يتم تعيينه بشكل صحيح إلى Temporal.Instant (وقت UTC) دقيق.

عندما تكون لديك هذه العناصر الثلاثة، يمكنك تحديد لحظة معينة لا لبس فيها على الخط الزمني، بغض النظر عن مكان تشغيل تطبيقك أو ما هي المنطقة الزمنية المحلية للمستخدم. هذا يجعل ZonedDateTime مثاليًا لأي عملية تاريخ ووقت تحتاج إلى تقديمها أو حسابها بالنسبة لمنطقة زمنية معينة.

إنشاء كائنات ZonedDateTime: أمثلة عملية

هناك عدة طرق لإنشاء كائن Temporal.ZonedDateTime، اعتمادًا على بيانات البداية لديك. دعنا نستكشف الطرق الأكثر شيوعًا مع أمثلة عالمية.

1. من الوقت الحالي

للحصول على التاريخ والوقت الحاليين في منطقة زمنية معينة، استخدم Temporal.ZonedDateTime.now(). يمكنك اختياريًا تمرير معرّف منطقة زمنية.

            
// Get the current ZonedDateTime in the system's default time zone
const nowInSystemTimeZone = Temporal.ZonedDateTime.now();
console.log(`Current time (system): ${nowInSystemTimeZone.toString()}`);
// Example output: 2023-10-27T14:30:45.123456789+02:00[Europe/Berlin]

// Get the current ZonedDateTime explicitly for 'Europe/London'
const nowInLondon = Temporal.ZonedDateTime.now('Europe/London');
console.log(`Current time (London): ${nowInLondon.toString()}`);
// Example output: 2023-10-27T13:30:45.123456789+01:00[Europe/London]

// Get the current ZonedDateTime explicitly for 'Asia/Tokyo'
const nowInTokyo = Temporal.ZonedDateTime.now('Asia/Tokyo');
console.log(`Current time (Tokyo): ${nowInTokyo.toString()}`);
// Example output: 2023-10-27T21:30:45.123456789+09:00[Asia/Tokyo]

            

              
                Copy
              
            
          

لاحظ كيف تمنحك now() اللحظة الحالية، ولكنها تنسقها وفقًا للمنطقة الزمنية المحددة، بما في ذلك الإزاحة الصحيحة في تلك اللحظة.

2. من مكونات محددة

يمكنك إنشاء ZonedDateTime من خلال توفير مكونات التاريخ والوقت الفردية الخاصة به، جنبًا إلى جنب مع المنطقة الزمنية المطلوبة. غالبًا ما يتم ذلك باستخدام الطريقة الثابتة from().

            
// Define a PlainDateTime for a specific event
const plainDateTime = Temporal.PlainDateTime.from({ year: 2024, month: 3, day: 15, hour: 9, minute: 0 });

// Create a ZonedDateTime for this event in New York
const eventInNewYork = Temporal.ZonedDateTime.from({
  plainDateTime: plainDateTime,
  timeZone: 'America/New_York',
});
console.log(`Event in New York: ${eventInNewYork.toString()}`);
// Expected output: 2024-03-15T09:00:00-04:00[America/New_York] (assuming DST is active in March)

// Create the same event in Mumbai, India
const eventInMumbai = Temporal.ZonedDateTime.from({
  year: 2024, month: 3, day: 15, hour: 9, minute: 0,
  timeZone: 'Asia/Kolkata' // IANA ID for Mumbai/India
});
console.log(`Event in Mumbai: ${eventInMumbai.toString()}`);
// Expected output: 2024-03-15T09:00:00+05:30[Asia/Kolkata]

            

              
                Copy
              
            
          

تحدد هذه الطريقة صراحةً وقت ساعة الحائط والمنطقة الزمنية التي ينتمي إليها، مما يزيل كل الغموض.

3. من PlainDateTime و TimeZone

إذا كان لديك بالفعل Temporal.PlainDateTime (تاريخ ووقت بدون منطقة زمنية)، فيمكنك بسهولة تحويله إلى ZonedDateTime عن طريق تحديد المنطقة الزمنية.

            
// A PlainDateTime representing 5 PM on November 1st, 2024
const fivePMMarch1st = Temporal.PlainDateTime.from('2024-11-01T17:00:00');

// Convert this to a ZonedDateTime in Sydney, Australia
const sydneyTime = fivePMMarch1st.toZonedDateTime('Australia/Sydney');
console.log(`Sydney time: ${sydneyTime.toString()}`);
// Expected output: 2024-11-01T17:00:00+11:00[Australia/Sydney] (Sydney should be on DST in November)

// Convert the same PlainDateTime to a ZonedDateTime in Sao Paulo, Brazil
const saoPauloTime = fivePMMarch1st.toZonedDateTime('America/Sao_Paulo');
console.log(`Sao Paulo time: ${saoPauloTime.toString()}`);
// Expected output: 2024-11-01T17:00:00-03:00[America/Sao_Paulo] (Sao Paulo should be on standard time in November)

            

              
                Copy
              
            
          

كائن PlainDateTime لا يتغير؛ بل يتم تفسيره ضمن سياق المنطقة الزمنية الجديدة.

4. من Instant و TimeZone

يمثل Instant نقطة زمنية عالمية وشاملة. يمكنك تحويل Instant إلى ZonedDateTime عن طريق توفير منطقة زمنية مستهدفة، قائلًا بفعالية، "ما هو الوقت والتاريخ الذي كان عليه في هذه المنطقة الزمنية في تلك اللحظة العالمية؟"

            
// A specific instant in time (e.g., a globally logged event)
const globalInstant = Temporal.Instant.from('2023-10-27T12:00:00Z'); // 12 PM UTC

// Show this instant in Berlin
const berlinTime = globalInstant.toZonedDateTime('Europe/Berlin');
console.log(`Berlin time: ${berlinTime.toString()}`);
// Expected output: 2023-10-27T14:00:00+02:00[Europe/Berlin]

// Show the same instant in Mexico City
const mexicoCityTime = globalInstant.toZonedDateTime('America/Mexico_City');
console.log(`Mexico City time: ${mexicoCityTime.toString()}`);
// Expected output: 2023-10-27T06:00:00-06:00[America/Mexico_City]

            

              
                Copy
              
            
          

هذا أمر بالغ الأهمية لعرض الأحداث المخزنة بتوقيت UTC للمستخدمين في سياقاتهم المحلية.

5. تحليل السلاسل النصية

يمكن لـ Temporal.ZonedDateTime أيضًا تحليل تنسيقات سلاسل نصية محددة، لا سيما تنسيق ISO 8601 الموسع الذي يتضمن معلومات المنطقة الزمنية.

            
// String with explicit time zone and offset
const parisMeeting = Temporal.ZonedDateTime.from('2023-12-25T09:30:00+01:00[Europe/Paris]');
console.log(`Paris meeting: ${parisMeeting.toString()}`);
// Expected output: 2023-12-25T09:30:00+01:00[Europe/Paris]

// String with just time zone, Temporal will determine the correct offset
const dubaiLaunch = Temporal.ZonedDateTime.from('2024-01-15T14:00:00[Asia/Dubai]');
console.log(`Dubai launch: ${dubaiLaunch.toString()}`);
// Expected output: 2024-01-15T14:00:00+04:00[Asia/Dubai]

            

              
                Copy
              
            
          

التحليل قوي وموحد، على عكس كائن Date القديم، مما يجعله موثوقًا به لاستيعاب بيانات التاريخ/الوقت من مصادر مختلفة.

إجراء حسابات تراعي المنطقة الزمنية

تتألق القوة الحقيقية لـ ZonedDateTime عند إجراء الحسابات. إن عدم قابلية Temporal للتغيير والتعامل الصريح مع المناطق الزمنية يعنيان أن العمليات يمكن التنبؤ بها ودقيقة، حتى في السيناريوهات المعقدة مثل انتقالات التوقيت الصيفي.

1. إضافة وطرح المدد الزمنية

يمكنك إضافة أو طرح كائنات Temporal.Duration من ZonedDateTime. ستراعي العملية الحسابية بشكل صحيح قواعد المنطقة الزمنية المرتبطة، بما في ذلك التوقيت الصيفي.

            
// Start time: March 9th, 2024, 10 AM in New York (before DST spring forward)
const startTimeNY = Temporal.ZonedDateTime.from('2024-03-09T10:00:00[America/New_York]');
console.log(`Start Time (NY): ${startTimeNY.toString()}`); // 2024-03-09T10:00:00-05:00[America/New_York]

// Add 2 days and 5 hours. DST in NY typically springs forward in early March.
const durationToAdd = Temporal.Duration.from({ days: 2, hours: 5 });
const endTimeNY = startTimeNY.add(durationToAdd);
console.log(`End Time (NY): ${endTimeNY.toString()}`);
// Expected output: 2024-03-11T16:00:00-04:00[America/New_York]
// Explanation: March 10th is the DST transition. Adding 2 days + 5 hours, the clock jumps forward.
// The calculation correctly accounts for the lost hour during DST transition.

// Example in a non-DST observing timezone (e.g., Asia/Shanghai)
const startTimeShanghai = Temporal.ZonedDateTime.from('2024-03-09T10:00:00[Asia/Shanghai]');
console.log(`Start Time (Shanghai): ${startTimeShanghai.toString()}`); // 2024-03-09T10:00:00+08:00[Asia/Shanghai]
const endTimeShanghai = startTimeShanghai.add(durationToAdd);
console.log(`End Time (Shanghai): ${endTimeShanghai.toString()}`);
// Expected output: 2024-03-11T15:00:00+08:00[Asia/Shanghai] (No DST adjustment needed)

            

              
                Copy
              
            
          

هذا التعامل التلقائي مع التوقيت الصيفي يغير قواعد اللعبة، ويزيل مصدرًا رئيسيًا للأخطاء.

2. تغيير المناطق الزمنية (تحويل الوقت)

واحدة من أكثر العمليات العالمية تكرارًا هي تحويل لحظة معينة في منطقة زمنية إلى أخرى. يجعل ZonedDateTime هذا الأمر سهلاً باستخدام طريقة withTimeZone().

            
// A meeting scheduled for 9:00 AM in Paris on December 10th, 2023
const meetingInParis = Temporal.ZonedDateTime.from('2023-12-10T09:00:00[Europe/Paris]');
console.log(`Meeting in Paris: ${meetingInParis.toString()}`);
// Output: 2023-12-10T09:00:00+01:00[Europe/Paris]

// What time is this meeting for a colleague in Tokyo?
const meetingInTokyo = meetingInParis.withTimeZone('Asia/Tokyo');
console.log(`Meeting in Tokyo: ${meetingInTokyo.toString()}`);
// Output: 2023-12-10T17:00:00+09:00[Asia/Tokyo] (9 AM Paris + 8 hours difference = 5 PM Tokyo)

// And for a colleague in Mexico City?
const meetingInMexicoCity = meetingInParis.withTimeZone('America/Mexico_City');
console.log(`Meeting in Mexico City: ${meetingInMexicoCity.toString()}`);
// Output: 2023-12-10T02:00:00-06:00[America/Mexico_City] (9 AM Paris - 7 hours difference = 2 AM Mexico City)

            

              
                Copy
              
            
          

اللحظة الأساسية (النقطة الزمنية العالمية) تظل كما هي؛ يتغير فقط تمثيلها (التاريخ والوقت والإزاحة) ليعكس قواعد المنطقة الزمنية الجديدة.

3. مقارنة كائنات ZonedDateTime

مقارنة كائنين من ZonedDateTime أمر مباشر لأنهما يمثلان لحظة زمنية لا لبس فيها. يمكنك استخدام طرق مثل equals()، before()، after()، والطريقة الثابتة Temporal.ZonedDateTime.compare().

            
const eventA = Temporal.ZonedDateTime.from('2023-11-05T10:00:00[Europe/London]');
const eventB = Temporal.ZonedDateTime.from('2023-11-05T09:00:00[America/New_York]');

// Event A (London) is 10:00 AM (+00:00 or +01:00 depending on DST, let's assume +00:00 for Nov)
// Event B (New York) is 09:00 AM (-04:00 or -05:00 depending on DST, let's assume -05:00 for Nov)
// If London is GMT, then Event A is effectively 10:00 UTC.
// If New York is EST, then Event B is effectively 14:00 UTC (9 AM + 5 hours).
// So Event A is *before* Event B.

console.log(`Are events equal? ${eventA.equals(eventB)}`); // false
console.log(`Is Event A before Event B? ${eventA.before(eventB)}`); // true
console.log(`Is Event A after Event B? ${eventA.after(eventB)}`);   // false

const comparisonResult = Temporal.ZonedDateTime.compare(eventA, eventB);
console.log(`Comparison result (A vs B): ${comparisonResult}`); // -1 (A is before B)

            

              
                Copy
              
            
          

يوضح هذا أن المقارنات تستند إلى اللحظة العالمية الفعلية، وليس فقط وقت ساعة الحائط في مناطق زمنية قد تكون مختلفة.

4. التعامل مع انتقالات التوقيت الصيفي (DST)

أحد أكثر جوانب التعامل مع الوقت تعقيدًا هو التوقيت الصيفي. يفهم ZonedDateTime ويطبق قواعد التوقيت الصيفي للمنطقة الزمنية المحددة بشكل متأصل. عند إجراء الإضافات أو التحويلات، يقوم تلقائيًا بضبط الإزاحة.

التقديم للأمام (تقفز الساعات للأمام)

            
// March 10, 2024, in New York, 1:30 AM (30 minutes before DST starts)
const beforeSpringForward = Temporal.ZonedDateTime.from('2024-03-10T01:30:00[America/New_York]');
console.log(`Before DST: ${beforeSpringForward.toString()}`); // 2024-03-10T01:30:00-05:00[America/New_York]

// Add 1 hour. This crosses the DST boundary (2:00 AM becomes 3:00 AM).
const afterSpringForward = beforeSpringForward.add({ hours: 1 });
console.log(`After DST (add 1 hour): ${afterSpringForward.toString()}`);
// Expected: 2024-03-10T03:30:00-04:00[America/New_York]
// The clock effectively skipped from 1:59:59 to 3:00:00, so adding an hour to 1:30 AM lands on 3:30 AM.

            

              
                Copy
              
            
          

التأخير للخلف (تقفز الساعات للخلف)

            
// November 3, 2024, in New York, 1:30 AM (30 minutes before DST ends)
const beforeFallBack = Temporal.ZonedDateTime.from('2024-11-03T01:30:00[America/New_York]');
console.log(`Before DST Fall Back: ${beforeFallBack.toString()}`); // 2024-11-03T01:30:00-04:00[America/New_York]

// Add 1 hour. This crosses the DST boundary (2:00 AM appears twice).
const afterFallBack = beforeFallBack.add({ hours: 1 });
console.log(`After DST (add 1 hour): ${afterFallBack.toString()}`);
// Expected: 2024-11-03T01:30:00-05:00[America/New_York]
// The clock effectively went from 1:59:59-04:00 to 1:00:00-05:00. So adding 1 hour to 1:30 AM-04:00 results in 1:30 AM-05:00.

            

              
                Copy
              
            
          

يتعامل Temporal بشكل صحيح مع هذه التحولات المعقدة، والتي كانت مصدرًا رئيسيًا للأخطاء مع كائن Date القديم.

إزالة الغموض للأوقات الغامضة/غير الموجودة

أثناء انتقالات التوقيت الصيفي، يمكن أن يكون وقت ساعة الحائط غير موجود (التقديم للأمام) أو غامضًا (التأخير للخلف، حيث يحدث وقت معين مرتين). يوفر Temporal خيار disambiguation عند تحويل PlainDateTime إلى ZonedDateTime:

• 'compatible' (الافتراضي): يهدف إلى التعيين الأكثر طبيعية. بالنسبة للأوقات غير الموجودة، فإنه 'يتقدم' إلى الوقت الصالح التالي. بالنسبة للأوقات الغامضة، فإنه يختار الإزاحة الأبكر.
• 'earlier': يختار دائمًا الوقت/الإزاحة الصالح الأبكر.
• 'later': يختار دائمًا الوقت/الإزاحة الصالح الأخير.
• 'reject': يطلق خطأ إذا كان الوقت غير موجود أو غامض.

            
const ambiguousTime = Temporal.PlainDateTime.from('2024-11-03T01:30:00'); // 1:30 AM during Fall Back
const timeZoneNY = 'America/New_York';

// Default (compatible) will pick the earlier offset
const zdtCompatible = ambiguousTime.toZonedDateTime(timeZoneNY, { disambiguation: 'compatible' });
console.log(`Compatible (earlier offset): ${zdtCompatible.toString()}`); // 2024-11-03T01:30:00-04:00[America/New_York]

// Explicitly pick the later offset
const zdtLater = ambiguousTime.toZonedDateTime(timeZoneNY, { disambiguation: 'later' });
console.log(`Later offset: ${zdtLater.toString()}`); // 2024-11-03T01:30:00-05:00[America/New_York]

// Reject ambiguous times
try {
  ambiguousTime.toZonedDateTime(timeZoneNY, { disambiguation: 'reject' });
} catch (e) {
  console.error(`Rejected ambiguous time: ${e.message}`); // Will throw if time is ambiguous
}

            

              
                Copy
              
            
          

هذا المستوى من التحكم ضروري للتطبيقات التي تتطلب الالتزام الصارم بالوقت، مثل الأنظمة المالية.

5. استخراج المكونات والتنسيق

يمكنك بسهولة استخراج المكونات الفردية (السنة، الشهر، اليوم، الساعة، إلخ) من ZonedDateTime. عند العرض للمستخدمين، سترغب عادةً في تنسيقه في سلسلة نصية قابلة للقراءة البشرية.

            
const exampleZDT = Temporal.ZonedDateTime.from('2024-07-20T14:30:00[Europe/Berlin]');

console.log(`Year: ${exampleZDT.year}`);      // 2024
console.log(`Month: ${exampleZDT.month}`);     // 7
console.log(`Day: ${exampleZDT.day}`);         // 20
console.log(`Hour: ${exampleZDT.hour}`);       // 14
console.log(`Offset: ${exampleZDT.offset}`);   // +02:00
console.log(`Time Zone ID: ${exampleZDT.timeZoneId}`); // Europe/Berlin

// For human-readable output, use toLocaleString() (which is locale-aware)
console.log(`Formatted (default locale): ${exampleZDT.toLocaleString()}`);
// Example: 20.07.2024, 14:30:00 MESZ

// Or with specific options for a global audience
console.log(exampleZDT.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long' }));
// Example: Saturday, July 20, 2024 at 2:30:00 PM Central European Summer Time

// Or for a more machine-readable, precise output, use toString()
console.log(`ISO String: ${exampleZDT.toString()}`);
// Output: 2024-07-20T14:30:00+02:00[Europe/Berlin]

            

              
                Copy
              
            
          

تعتبر toLocaleString() قوية لتكييف عرض التواريخ والأوقات مع التقاليد الثقافية المختلفة، مستفيدة من واجهة برمجة تطبيقات Intl في المتصفح.

سيناريوهات عالمية شائعة وحلول مع ZonedDateTime

دعنا نلقي نظرة على كيفية توفير ZonedDateTime لحلول أنيقة لتحديات التطوير العالمية اليومية.

1. جدولة الاجتماعات عبر القارات

تحدي كلاسيكي: تنسيق اجتماع بين فرق منتشرة في جميع أنحاء العالم.

المشكلة:

مديرة مشروع في باريس تحتاج إلى جدولة تحديث حالة لمدة 30 دقيقة مع أعضاء الفريق في نيويورك وبكين وسيدني. تريد أن تبدأه في الساعة 10:00 صباحًا بتوقيت باريس يوم الاثنين. ما هو الوقت الذي سيكون عليه ذلك للجميع؟

الحل:

حدد بداية الاجتماع بتوقيت باريس باستخدام ZonedDateTime، ثم قم بتحويله إلى المناطق الزمنية لأعضاء الفريق الآخرين. هذا يضمن أن يرى الجميع وقت البدء المحلي الصحيح.

            
const meetingDate = Temporal.PlainDate.from('2024-04-15'); // A Monday
const meetingTime = Temporal.PlainTime.from('10:00:00'); // 10:00 AM

// 1. Define the meeting start in Paris
const meetingStartParis = Temporal.ZonedDateTime.from({
  plainDateTime: Temporal.PlainDateTime.from({ year: 2024, month: 4, day: 15, hour: 10, minute: 0 }),
  timeZone: 'Europe/Paris'
});
console.log(`Meeting starts for Paris: ${meetingStartParis.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output: 4/15/2024, 10:00 AM CEST

// 2. Convert for New York (America/New_York)
const meetingStartNY = meetingStartParis.withTimeZone('America/New_York');
console.log(`Meeting starts for New York: ${meetingStartNY.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output: 4/15/2024, 4:00 AM EDT (10 AM Paris - 6 hours difference = 4 AM NY)

// 3. Convert for Beijing (Asia/Shanghai is close, used as typical China time zone)
const meetingStartBeijing = meetingStartParis.withTimeZone('Asia/Shanghai');
console.log(`Meeting starts for Beijing: ${meetingStartBeijing.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output: 4/15/2024, 4:00 PM CST (10 AM Paris + 6 hours difference = 4 PM Beijing)

// 4. Convert for Sydney (Australia/Sydney)
const meetingStartSydney = meetingStartParis.withTimeZone('Australia/Sydney');
console.log(`Meeting starts for Sydney: ${meetingStartSydney.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output: 4/16/2024, 12:00 AM AEST (10 AM Paris + 14 hours difference = 12 AM next day Sydney)

// To show the meeting end time for Paris
const meetingEndParis = meetingStartParis.add({ minutes: 30 });
console.log(`Meeting ends for Paris: ${meetingEndParis.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output: 4/15/2024, 10:30 AM CEST

            

              
                Copy
              
            
          

يزيل هذا النهج كل التخمينات، ويوفر لكل مشارك وقت اجتماعه المحلي الدقيق.

2. إدارة الأحداث وتذاكرها

تتطلب استضافة الأحداث أو الحفلات الموسيقية أو الندوات عبر الإنترنت العالمية أوقات بدء واضحة لا لبس فيها للحاضرين في جميع أنحاء العالم.

المشكلة:

يتم الإعلان عن مهرجان موسيقي عالمي عبر الإنترنت ليبدأ في "الساعة 8:00 مساءً يوم 1 أغسطس 2024" في لندن (Europe/London). كيف تعرض هذا بشكل صحيح لمستخدم يتصفح من طوكيو، اليابان، أو ريو دي جانيرو، البرازيل؟

الحل:

قم بتخزين وقت بدء الحدث كـ ZonedDateTime في منطقته الزمنية الرسمية. عندما يعرض المستخدم الحدث، قم بتحويله إلى المنطقة الزمنية المحلية لمتصفحه أو منطقة زمنية اختارها صراحةً.

            
// The official start time of the festival in London
const festivalStartLondon = Temporal.ZonedDateTime.from('2024-08-01T20:00:00[Europe/London]');
console.log(`Official Festival Start (London): ${festivalStartLondon.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long', timeZoneName: 'long' })}`);
// Output: Thursday, August 1, 2024 at 8:00:00 PM British Summer Time

// Assuming a user in Tokyo
const userTimeZoneTokyo = 'Asia/Tokyo';
const festivalStartTokyo = festivalStartLondon.withTimeZone(userTimeZoneTokyo);
console.log(`For a user in Tokyo: ${festivalStartTokyo.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long', timeZoneName: 'long' })}`);
// Output: Friday, August 2, 2024 at 4:00:00 AM Japan Standard Time

// Assuming a user in Rio de Janeiro
const userTimeZoneRio = 'America/Sao_Paulo'; // IANA ID for Rio/Brazil
const festivalStartRio = festivalStartLondon.withTimeZone(userTimeZoneRio);
console.log(`For a user in Rio de Janeiro: ${festivalStartRio.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long', timeZoneName: 'long' })}`);
// Output: Thursday, August 1, 2024 at 4:00:00 PM Brasilia Standard Time

            

              
                Copy
              
            
          

يضمن هذا أن يرى المستخدمون دائمًا وقت الحدث مترجمًا بشكل صحيح إلى سياقهم، مما يمنع الارتباك وفوات الأحداث.

3. تسجيل ومراجعة المعاملات العالمية

بالنسبة للأنظمة التي تتطلب دقة كرونولوجية مطلقة، مثل منصات التداول المالي أو تطبيقات البلوك تشين، يجب ختم كل حدث زمنيًا بشكل لا لبس فيه.

المشكلة:

تنشأ المعاملات من مراكز بيانات إقليمية مختلفة، لكل منها وقت خادم محلي خاص بها. كيف تضمن مسار تدقيق عالمي لا لبس فيه؟

الحل:

قم بتخزين الوقت الأساسي للحدث كـ Temporal.Instant (UTC). عند عرض هذه السجلات أو معالجتها في سياق إقليمي، قم بتحويل Instant إلى ZonedDateTime للمنطقة الزمنية ذات الصلة.

            
// A transaction occurred at a specific universal moment
const transactionInstant = Temporal.Instant.from('2023-10-27T15:30:45.123456789Z');
console.log(`Universal Transaction Instant: ${transactionInstant.toString()}`);
// Output: 2023-10-27T15:30:45.123456789Z

// Later, a user in Frankfurt needs to see when this happened in their local time
const frankfurtTime = transactionInstant.toZonedDateTime('Europe/Berlin');
console.log(`Transaction in Frankfurt: ${frankfurtTime.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long', timeZoneName: 'long' })}`);
// Output: Friday, October 27, 2023 at 5:30:45 PM Central European Summer Time

// A user in Singapore needs to see it in their local time
const singaporeTime = transactionInstant.toZonedDateTime('Asia/Singapore');
console.log(`Transaction in Singapore: ${singaporeTime.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long', timeZoneName: 'long' })}`);
// Output: Friday, October 27, 2023 at 11:30:45 PM Singapore Standard Time

            

              
                Copy
              
            
          

يوفر هذا النمط كلاً من الحقيقة العالمية (Instant) والمنظور المحلي (ZonedDateTime)، وهو أمر ضروري للتدقيق وإعداد التقارير القوية.

4. المواعيد النهائية لطلبات التجارة الإلكترونية

تحديد المواعيد النهائية للعروض الترويجية، أو الشحن في نفس اليوم، أو العروض الخاصة لقاعدة عملاء عالمية.

المشكلة:

يقدم موقع للتجارة الإلكترونية عرض "اطلب بحلول الساعة 5:00 مساءً اليوم للتسليم في اليوم التالي". يجب ترجمة هذا الموعد النهائي للعملاء في مناطق مختلفة.

الحل:

حدد الموعد النهائي الأساسي في منطقة زمنية تجارية محددة. لكل عميل، قم بتحويل هذا الموعد النهائي إلى منطقته الزمنية المحلية وحساب الوقت المتبقي.

            
// Define the daily cutoff time in the fulfillment center's time zone (e.g., US Eastern Time)
const cutoffTimePlain = Temporal.PlainTime.from('17:00:00'); // 5 PM
const todayInFulfillment = Temporal.ZonedDateTime.now('America/New_York');
const todayDate = todayInFulfillment.toPlainDate();

const dailyCutoffNY = Temporal.ZonedDateTime.from({
  plainDate: todayDate,
  plainTime: cutoffTimePlain,
  timeZone: 'America/New_York'
});
console.log(`Daily cutoff (New York): ${dailyCutoffNY.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);

// For a customer in Los Angeles (America/Los_Angeles)
const customerLA = dailyCutoffNY.withTimeZone('America/Los_Angeles');
console.log(`Customer in Los Angeles: Order by ${customerLA.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output will show 2:00 PM for the LA customer for the same cutoff instant.

// For a customer in London (Europe/London)
const customerLondon = dailyCutoffNY.withTimeZone('Europe/London');
console.log(`Customer in London: Order by ${customerLondon.toLocaleString('en-US', { timeStyle: 'short', dateStyle: 'medium', timeZoneName: 'short' })}`);
// Output will show 10:00 PM for the London customer for the same cutoff instant.

// Calculate time remaining until cutoff for a user in their local timezone (e.g., Los Angeles)
const nowInLA = Temporal.ZonedDateTime.now('America/Los_Angeles');
const timeRemaining = nowInLA.until(customerLA);
console.log(`Time remaining for LA customer: ${timeRemaining.toString()}`);

            

              
                Copy
              
            
          

يسلط هذا السيناريو الضوء على كيف يسمح لك ZonedDateTime بتعريف قاعدة عمل واحدة ومتسقة ثم تقديمها بدقة في سياقات محلية متنوعة.

أفضل الممارسات لاستخدام ZonedDateTime في التطبيقات العالمية

لتحقيق أقصى استفادة من Temporal.ZonedDateTime وضمان أن تكون تطبيقاتك جاهزة عالميًا حقًا، ضع في اعتبارك أفضل الممارسات التالية:

• تخزين اللحظات غير المرتبطة بالوقت كـ Temporal.Instant (UTC): لأي حدث يمثل نقطة زمنية عالمية واحدة، قم دائمًا بتخزينه كـ Temporal.Instant (وهو UTC بطبيعته). هذا هو "مصدر الحقيقة" الخاص بك. قم بالتحويل إلى ZonedDateTime فقط عندما تحتاج إلى إجراء حسابات تراعي المنطقة الزمنية أو عرضها في سياق خاص بالمستخدم.

              
  // Store in database
  const eventTimestamp = Temporal.Instant.now(); // Always UTC
  // Retrieve from database
  const retrievedInstant = Temporal.Instant.from('2023-10-27T15:30:45.123456789Z');
      
              
  
                
                  Copy
                
              
            

• استخدام ZonedDateTime للعرض المواجه للمستخدم والمنطق الخاص بالمنطقة الزمنية: عندما تحتاج إلى إظهار تاريخ ووقت للمستخدم، أو عندما يعتمد منطق العمل على أوقات ساعة حائط محددة (على سبيل المثال، "يفتح الساعة 9 صباحًا بالتوقيت المحلي")، فإن ZonedDateTime هو الخيار الصحيح. قم بتحويل Instant (مصدر الحقيقة الخاص بك) إلى المنطقة الزمنية المفضلة للمستخدم باستخدام instant.toZonedDateTime(userTimeZone).

              
  const userTimeZone = Temporal.TimeZone.from('America/New_York');
  const displayTime = retrievedInstant.toZonedDateTime(userTimeZone);
  console.log(displayTime.toLocaleString('en-US', { dateStyle: 'medium', timeStyle: 'short' }));
      
              
  
                
                  Copy
                
              
            

• تحديد المناطق الزمنية بشكل صريح: لا تعتمد أبدًا على الإعدادات الافتراضية للنظام للعمليات الحرجة. قم دائمًا بتمرير معرّف منطقة زمنية IANA (مثل، "Europe/London"، "Asia/Shanghai") عند إنشاء أو تحويل كائنات ZonedDateTime. إذا كنت تعرض لمستخدم، فحدد منطقته الزمنية إما من واجهات برمجة تطبيقات المتصفح (Intl.DateTimeFormat().resolvedOptions().timeZone) أو من إعداد تفضيل المستخدم.

              
  // Good: Explicit time zone
  const specificZDT = Temporal.ZonedDateTime.from('2023-11-01T10:00:00[Europe/Berlin]');
  
  // Potentially problematic if not intentionally desired (depends on system config)
  // const implicitZDT = Temporal.ZonedDateTime.now();
      
              
  
                
                  Copy
                
              
            

• كن على دراية بتغييرات التوقيت الصيفي (ولكن دع Temporal يتعامل معها): بينما يتعامل Temporal مع التوقيت الصيفي تلقائيًا، فمن الأهمية بمكان فهم كيفية تأثيره على المدد وتحويلات الوقت. على سبيل المثال، قد لا تؤدي إضافة 24 ساعة أثناء "التقديم للأمام" في التوقيت الصيفي إلى نفس وقت ساعة الحائط في اليوم التالي. هذا سلوك صحيح، ولكنه يمكن أن يكون مفاجئًا إذا لم يتم فهمه.
• تثقيف فريقك: تأكد من أن جميع المطورين العاملين على تطبيق عالمي يفهمون أنواع Temporal المختلفة ومتى يستخدمون كل منها. يمكن أن تؤدي حالات سوء الفهم إلى أخطاء جديدة، حتى مع وجود واجهة برمجة تطبيقات متفوقة.
• الاختبار الشامل، خاصة حول انتقالات التوقيت الصيفي: أنشئ حالات اختبار محددة للأوقات قبل وأثناء وبعد تغييرات التوقيت الصيفي في مناطق زمنية مختلفة ذات صلة بقاعدة المستخدمين لديك. اختبر التحويلات بين المناطق الزمنية المختلفة بشكل كبير.
• النظر في تفضيلات المستخدم لعرض المنطقة الزمنية: بينما يمكن أن يمنحك Temporal.ZonedDateTime.now() و Intl.DateTimeFormat().resolvedOptions().timeZone المنطقة الزمنية لنظام المستخدم، فإن السماح للمستخدمين بتحديد منطقتهم الزمنية المفضلة صراحة يمكن أن يعزز تجربتهم، خاصة للمسافرين أو الذين قد لا تعكس منطقة زمنية نظامهم تفضيلهم الفعلي.
• استفد من Temporal.Calendar للتقاويم غير الميلادية (إن أمكن): إذا كان تطبيقك يحتاج إلى تلبية احتياجات الثقافات التي تستخدم تقاويم غير ميلادية (مثل التقاويم اليابانية، الإسلامية، البوذية التايلاندية)، فيمكن أيضًا إنشاء ZonedDateTime بتقويم محدد، مما يضمن تمثيل التاريخ الصحيح في تلك الأنظمة. وهذا يعزز الشمولية العالمية بشكل أكبر.

              
  const japaneseNewYear = Temporal.ZonedDateTime.from({
    year: 2024, month: 1, day: 1, hour: 0, minute: 0,
    timeZone: 'Asia/Tokyo', calendar: 'japanese'
  });
  console.log(japaneseNewYear.toLocaleString('ja-JP', { dateStyle: 'full', timeStyle: 'full', calendar: 'japanese' }));
      
              
  
                
                  Copy
                
              
            

دعم المتصفحات والـ Polyfills

اعتبارًا من أواخر عام 2023 / أوائل عام 2024، وصلت Temporal API إلى المرحلة 3 من عملية TC39، مما يعني أن مواصفاتها مستقرة إلى حد كبير ولكنها لم تنفذ بعد عالميًا في جميع محركات المتصفحات بشكل افتراضي. هذا مجال سريع التطور، لذا من الضروري التحقق من أحدث جداول التوافق.

للاستخدام الفوري في بيئات الإنتاج، خاصة للتطبيقات العالمية ذات الأهمية الحيوية، يوصى بشدة باستخدام polyfill. يتيح لك polyfill الرسمي لـ Temporal البدء في استخدام واجهة برمجة التطبيقات اليوم عبر مجموعة واسعة من إصدارات المتصفحات و Node.js، مما يوفر سلوكًا متسقًا حتى يصبح الدعم الأصلي منتشرًا.

يمكنك العثور على polyfill الرسمي والمزيد من المعلومات حول استخدامه عبر npm:

            
npm install @js-temporal/polyfill

            

              
                Copy
              
            
          

ثم، عادةً في نقطة الدخول لتطبيقك:

            
import '@js-temporal/polyfill/global';
// Now you can use Temporal directly
const now = Temporal.ZonedDateTime.now('Europe/London');

            

              
                Copy
              
            
          

ارجع دائمًا إلى الوثائق الرسمية لـ Temporal ومستودع GitHub الخاص بالـ polyfill للحصول على أحدث تعليمات التثبيت والاستخدام.

الخاتمة: تبني Temporal لتجربة وقت عالمية متناغمة

لطالما كانت تحديات التعامل مع التواريخ والأوقات في سياق عالمي نقطة مؤلمة لمطوري JavaScript. كائن Date القديم، بغموضه وقابليته للتغيير، غالبًا ما أدى إلى أخطاء دقيقة ولكنها كبيرة. مع ظهور واجهة برمجة التطبيقات JavaScript Temporal API، وتحديدًا Temporal.ZonedDateTime، لدينا الآن أداة قوية وصريحة وموثوقة للتغلب على هذه التعقيدات.

من خلال فهم مكوناته الأساسية والاستفادة من كائناته غير القابلة للتغيير، يمكن للمطورين إجراء حسابات تراعي المنطقة الزمنية بثقة، وتحويل الأوقات عبر القارات، والتعامل بدقة مع انتقالات التوقيت الصيفي، وتقديم معلومات التاريخ والوقت بشكل لا لبس فيه للمستخدمين في جميع أنحاء العالم. سواء كنت تبني منصة تجارة إلكترونية عالمية، أو لوحة تحكم تحليلية في الوقت الفعلي، أو تطبيق جدولة تعاوني، فإن ZonedDateTime هو أصل لا غنى عنه لإنشاء برامج دولية وقوية حقًا.

إن الرحلة نحو واجهة برمجة تطبيقات أكثر دقة وبديهية للتاريخ/الوقت في JavaScript جارية على قدم وساق. ابدأ في استكشاف Temporal اليوم، وادمجها في مشاريعك بمساعدة الـ polyfills، وارتقِ بتطبيقاتك لتقديم تجربة زمنية متناغمة وخالية من العيوب لكل مستخدم، في كل مكان.